CVL KRA Upload API

This document highlights the CVL KRA Upload API details.

Objective

The CVL KRA Upload API manages the submission and modification of KYC applications in the KYC registration agency. The API supports new KYC submissions, and modifications based on the application's status.

API URL

https://ind-engine.thomas.hyperverge.co/v1/async/CVLKRAUpload

API Endpoint

CVLKRAUpload

Overview

The API is RESTful and uses standard HTTP verbs and status codes. The responses are in JSON format and you should upload all images and files as form-data through a POST request.

Authentication

You need a unique pair of application ID (appId) and application key (appKey) from HyperVerge to verify your identity for accessing the API.

API Request Details

Method - POST

Headers

Parameter	Mandatory or Optional	Description	Allowed Values
content-type	Mandatory	This parameter defines the media type for the request payload	application/json
appId	Mandatory	The application identifier shared by HyperVerge. You can find the details in the dashboard's credentials tab.	This should be a unique value.
appKey	Mandatory	The application key shared by HyperVerge. You can find the details in the dashboard's credentials tab.	This should be a unique value.
transactionId	Mandatory	A unique identifier for tracking a user journey	This should be both unique and easily associated with the user's journey in your application(s)

Inputs

The following table provides the details of the parameters required for the API's request body:

Parameter	Description	Mandatory or Optional	Allowed Values
appUpdtflg	The value should be selected based on the current status of the KYC application (obtained from the CVL Search and Verify API). How to choose the correct value: New: Use for first-time KYC submissions or when no existing KYC is found Modify with documents: Use when updating KYC details that require document verification (e.g., address changes) Interop Modification: Use when the KYC exists in other KRAs and needs modification For detailed mapping based on application status, refer to the appStatus and appUpdtflg mapping table below.	Mandatory	new modify_with_doc interop_modification
kraAgency	Specifies the KYC Registration Agency (KRA) that will handle the KYC application	Mandatory	CVLKRA NDML DOTEX CAMS KARVY bse
appType	Specifies whether the application is for an individual applicant or a non-individual applicant Note From this point forward, 'user' refers to an individual applicant, and 'organization' refers to a non-individual applicant.	Mandatory	individual non_individual
appNo	The unique number generated for each KYC application	Optional	Not Applicable
appDate	The date on which the KYC application was submitted	Mandatory	The input format for this parameter should be 'DD-MM-YYYY'
appPanNo	The PAN of the user	Mandatory	Not Applicable
appPanCopy	The value is 'yes' if the user's PAN card image has been submitted; otherwise, the value is 'no'	Mandatory	yes or no
appExmt	The value is 'no' if the user's PAN card image has been submitted, and 'yes' if user's exempted from submitting the PAN card	Mandatory	yes or no
appExmtCat	The user was exempted from submitting their PAN card image due to one or more valid reasons. For the complete list of exemption criteria, please refer to this page	Optional	Allowed Values
appExmtIdProof	The document used as Proof of Identity. For the complete list of valid ID proof documents, please refer to this page.	Mandatory	Allowed Values
appIpvFlag	The value is 'yes' if an In-Person Verification (IPV) was conducted for the KYC application; 'no' if not conducted, or 'exempted' if completed online.	Mandatory	yes no exempted
appIpvDate	The date when the IPV was conducted, if applicable	Optional	The input format for this parameter should be 'DD-MM-YYYY'
appGen	The gender of the user. Valid values are F (Female), M (Male), and T (Transgender)	Mandatory	F M T
appName	The name of the user	Mandatory	Not Applicable
appFName	The name of the user's father/husband	Mandatory	Not Applicable
appRegno	The registration number of the organization	Optional	Not Applicable
appDobIncorp	The date of birth of the user or the incorporation date of the organization	Mandatory	The input format for this parameter should be 'DD-MM-YYYY'
appCommenceDt	The date when the organization commenced business	Optional	The input format for this parameter should be 'DD-MM-YYYY'
appNationality	The nationality of the user	Mandatory	indian others
appOthNationality	The user's nationality, if not Indian; for example, Argentina, Greece, etc	Optional. (Mandatory if user nationality is 'Others')	Not Applicable
appCompStatus	The type of organization. For the complete list of different types of valid organizations, please refer to this page	Mandatory	Allowed Values
appOthCompStatus	The status of the company, if 'Others' (as from appCompStatus's value)	Optional	Not Applicable
appResStatus	The residential status of the user. It could be one of the following: Resident Individual Non-Resident Individual Foreign National QFI Eligible Foreign Investor - Category III	Mandatory	resident_indian_individual non_resident_indian_individual foreign_national qfi eligible_foreign_investor_category
appResStatusProof	The address proof for a non-residential Indian or person of Indian origin. It could be one of the following documents: Passport PIO Card OCI Card	Optional	passport PIO_card OCI_card
appUidNo	The last four digits of the UID/Aadhaar number of the user	Optional	Not Applicable
appCorAdd1	The first line of the correspondence address. It includes the house number and the street name.	Mandatory	Not Applicable
appCorAdd2	The second line of the correspondence address. It includes the district name.	Optional	Not Applicable
appCorAdd3	The third line of the correspondence address. It includes the name of the corresponding state.	Optional	Not Applicable
appCorCity	The correspondence city	Mandatory	Not Applicable
appCorPincd	The PIN code for the correspondence address	Mandatory	Not Applicable
appCorState	The correspondence state,if the user's nationality is Indian	Mandatory	Allowed Values
appCorCtry	The correspondence country	Mandatory	Not Applicable Default Value: India
appOffIsd	The ISD code for the user's office contact number	Optional	Not Applicable
appOffStd	The STD code for the user's office contact number	Optional	Not Applicable
appOffNo	The user's office contact number	Optional	Not Applicable
appResIsd	The ISD code for the user's residential contact number	Optional	Not Applicable
appResStd	The STD code for the user's residential contact number	Optional	Not Applicable
appResNo	The user's residential contact number	Optional	Not Applicable
appMobIsd	The ISD code for the user's mobile phone number	Optional	Not Applicable
appMobNo	The user's mobile phone number	Mandatory	Not Applicable
appFaxIsd	The ISD code for the user's fax number	Optional	Not Applicable
appFaxStd	The STD code for the user's fax number	Optional	Not Applicable
appFaxNo	The fax number for the user	Optional	Not Applicable
appEmail	The email address of the user	Mandatory	Not Applicable
appCorAddProof	The document serving as proof of the correspondence address. For the complete list of accepted documents, please refer to this page.	Mandatory	Allowed Values
appCorAddRef	The identification number linked to the correspondence address proof document. For instance, if the Aadhaar card is provided as the address proof, the Aadhaar number serves as the reference ID.	Optional	Not Applicable
appCorAddDt	The validity date of the corresponding address proof, as specified in the address proof document	Optional	The input format for this parameter should be 'DD-MM-YYYY'
appPerAddFlag	This flag indicates whether the permanent residential address matches the corresponding address. If they match, the corresponding address value is used; otherwise, the permanent address must be provided separately in the subsequent address parameters	Mandatory	yes, no
appPerAdd1	The first line of the permanent address. It includes the house number and the street name.	Mandatory	Not Applicable
appPerAdd2	The second line of the permanent address. It includes the name of the district.	Optional	Not Applicable
appPerAdd3	The third line of the permanent address. It includes the name of the state.	Optional	Not Applicable
appPerCity	The city of the permanent address	Mandatory	Not Applicable
appPerPincd	The PIN code for the permanent address	Mandatory	Not Applicable
appPerState	The state of the permanent address	Mandatory	Allowed Values
appPerCtry	The country of the permanent address	Mandatory	Not Applicable Default Value: India
appPerAddProof	The document serving as proof of the permanent address. For the complete list of accepted documents, please refer to this page.	Mandatory	Allowed Values
appPerAddRef	The identification number linked to the permanent address proof document. For instance, if the Aadhaar card is provided as the address proof, the Aadhaar number serves as the reference ID.	Optional	Not Applicable
appPerAddDt	The validity date of the permanent address proof, as specified in the address proof document	Optional	The input format for this parameter should be 'DD-MM-YYYY'
appIncome	The user's gross annual income, represented as a range. For more details on income slabs, please refer to this page.	Optional	Allowed Values
appOcc	The occupation of the user, specified by selecting a domain from this list.	Optional	Allowed Values
appOthOcc	The occupation details of the user, if 'Others' (as from appOcc's value)	Optional	Not Applicable
appPolConn	The PEP status of the user, which they can select based on the category that applies to them. The categories are: Not Politically Exposed Politically Exposed Person (PEP) Related to a Politically Exposed Person(RPEP)	Optional	not_applicable politically_exp_person related_politically_exp_person
appDocProof	The details of the documents submitted by the user: whether they are self-certified copies or true copies of the documents, or if they are exempted from submitting any documents altogether	Mandatory	self_certi_copies_submitted true_copies_received exempted
appInternalRef	Internal reference number for intermediaries	Optional	Not Applicable
appBranchCode	The branch code to which the KYC is attached	Optional	Not Applicable
appMarStatus	The marital status of the user, whether they are married or unmarried	Mandatory	married unmarried
appNetwrth	The net worth of the user or the organization	Optional	The input format for this parameter should be a numeric value
appNetworthDt	The net worth of the user or the organization as on date	Selectively Optional*	The input format for this parameter should be "DD-MM-YYYY" Note Selectively Optional*: This is optional if the gross annual income is specified for a user. If the net worth is provided for an organization, then this parameter is mandatory.
appIncorpPlc	The place of incorporation of the organization, if applicable	Optional	Not Applicable
appOtherInfo	Any additional information	Optional	Not Applicable
appIpvName	The name of the person who is carrying out the in-person verification(IPV), if applicable	Optional	Not Applicable
appIpvDesg	The designation of the person carrying out the IPV application	Optional	Not Applicable
appIpvOrgan	The organization of the individual who carried out the IPV application	Optional	Not Applicable
appKycMode	The mode of KYC verification. It could be one of the following: Normal(In-person) KYC e-KYC with OTP e-KYC with Biometric Online Data Entry and IPV Offline KYC - Aadhaar Digilocker	Mandatory	normal_kyc ekyc_with_otp ekyc_with_biometric online_data_entry offline_kyc digilocker
appVidNo	The Aadhaar Virtual ID Number of the user or organization	Optional	Not Applicable
appUidToken	The Aadhaar UID Token	Optional	Not Applicable
appVerNo	The version number	Optional	Not Applicable
appAuthName	The name of the Foreign Portfolio Investment (FPI) authorizer	Optional	Not Applicable
appAuthEmail	The email address of the FPI authorizer	Optional	Not Applicable
appAuthEmail1	The additional email address of the FPI authorizer	Optional	Not Applicable
appAuthEmail2	The additional email address of the FPI authorizer	Optional	Not Applicable
appAuthMobile	The mobile number of the FPI authorizer	Optional	Not Applicable
appAuthFpiConsent	The FPI consent for the authorized person, if any	Optional	yes or no
appAuthUboConsent	UBO consent for the authorized person, if any	Optional	yes or no
noOfKycRecords	The number of KYC records	Mandatory	Not Applicable
noOfAddldataRecords	The number of additional data records, if any	Optional	Not Applicable
pan	The Application Opening Form (AOF) containing all user details	Mandatory	Not Applicable
aadhaar	The Aadhaar in xml format	Mandatory	Not Applicable
appFatcaApplicableFlag	The confirmation on whether the application is subject to FATCA regulations	Mandatory	Yes or No

Request

The following code snippet demonstrates a standard curl request for the API:

curl --location --request POST 'https://ind-engine.thomas.hyperverge.co/v1/async/CVLKRAUpload' \
--header 'Content-Type: application/json' \
--header 'appId: <Enter_the_HyperVerge_appId>' \
--header 'appKey: <Enter_the_HyperVerge_appKey>' \
--header 'transactionId: <Enter_the_HyperVerge_transactionID>' \
--data '{
    "appUpdtflg": "<Enter_Update_Flag>",
    "kraAgency": "<Enter_the_KRA_undertaking_the_KYC_application>",
    "appType": "<Enter_Applicant_Type>",
    "appNo": "<Enter_Application_Number>",
    "appPanNo": "<Enter_the_PAN>",
    "appPanCopy": "<Enter_if_PAN_Copy_is_Submitted>",
    "appExmt": "<Enter_Exemption_Status>",
    "appExmtCat": "<Enter_Exemption_Category>",
    "appExmtIdProof": "<Enter_Exemption_ID_Proof>",
    "appIpvFlag": "<Enter_IPV_Flag>",
    "appIpvDate": "<Enter_IPV_Date_in_DD-MM-YYYY>",
    "appGen": "<Enter_Gender>",
    "appName": "<Enter_Name>",
    "appFName": "<Enter_Fathers_Name>",
    "appRegno": "<Enter_Registration_Number>",
    "appDobIncorp": "<Enter_Date_of_Birth_or_Incorporation_in_DD-MM-YYYY>",
    "appCommenceDt": "<Enter_Commencement_Date>",
    "appNationality": "<Enter_Nationality>",
    "appOthNationality": "<Enter_Other_Nationality_if_Applicable>",
    "appCompStatus": "<Enter_Company_Status>",
    "appOthCompStatus": "<Enter_Other_Company_Status>",
    "appResStatus": "<Enter_Residential_Status>",
    "appResStatusProof": "<Enter_Residential_Status_Proof>",
    "appUidNo": "<Enter_UID_Number>",
    "appCorAdd1": "<Enter_Correspondence_Address_Line_1>",
    "appCorAdd2": "<Enter_Correspondence_Address_Line_2>",
    "appCorAdd3": "<Enter_Correspondence_Address_Line_3>",
    "appCorCity": "<Enter_Correspondence_City>",
    "appCorPincd": "<Enter_Correspondence_Pincode>",
    "appCorState": "<Enter_Correspondence_State>",
    "appCorCtry": "<Enter_Correspondence_Country>",
    "appOffIsd": "<Enter_Office_ISD_Code>",
    "appOffStd": "<Enter_Office_STD_Code>",
    "appOffNo": "<Enter_Office_Number>",
    "appResIsd": "<Enter_Residence_ISD_Code>",
    "appResStd": "<Enter_Residence_STD_Code>",
    "appResNo": "<Enter_Residence_Number>",
    "appMobIsd": "<Enter_Mobile_ISD_Code>",
    "appMobNo": "<Enter_Mobile_Number>",
    "appFaxIsd": "<Enter_Fax_ISD_Code>",
    "appFaxStd": "<Enter_Fax_STD_Code>",
    "appFaxNo": "<Enter_Fax_Number>",
    "appEmail": "<Enter_Email>",
    "appCorAddProof": "<Enter_Correspondence_Address_Proof>",
    "appCorAddRef": "<Enter_Correspondence_Address_Reference>",
    "appCorAddDt": "<Enter_Correspondence_Address_Date>",
    "appPerAddFlag": "<Enter_if_Permanent_Address_is_Same_as_Correspondence>",
    "appPerAdd1": "<Enter_Permanent_Address_Line_1>",
    "appPerAdd2": "<Enter_Permanent_Address_Line_2>",
    "appPerAdd3": "<Enter_Permanent_Address_Line_3>",
    "appPerCity": "<Enter_Permanent_City>",
    "appPerPincd": "<Enter_Permanent_Pincode>",
    "appPerState": "<Enter_Permanent_State>",
    "appPerCtry": "<Enter_Permanent_Country>",
    "appPerAddProof": "<Enter_Permanent_Address_Proof>",
    "appPerAddRef": "<Enter_Permanent_Address_Reference>",
    "appPerAddDt": "<Enter_Permanent_Address_Date>",
    "appIncome": "<Enter_Gross_Annual_Income>",
    "appOcc": "<Enter_Occupation>",
    "appOthOcc": "<Enter_Other_Occupation>",
    "appPolConn": "<Enter_Political_Connection_Status>",
    "appDocProof": "<Enter_Document_Proof_Status>",
    "appInternalRef": "<Enter_Internal_Reference>",
    "appBranchCode": "<Enter_Branch_Code>",
    "appMarStatus": "<Enter_Marital_Status>",
    "appNetwrth": "<Enter_Net_Worth>",
    "appNetworthDt": "<Enter_Net_Worth_Date_in_DD-MM-YYYY>",
    "appIncorpPlc": "<Enter_Incorporation_Place>",
    "appOtherInfo": "<Enter_Other_Information>",
    "appFiller1": "<Enter_Filler_Field_1>",
    "appFiller2": "<Enter_Filler_Field_2>",
    "appFiller3": "<Enter_Filler_Field_3>",
    "appIpvName": "<Enter_IPV_Name>",
    "appIpvDesg": "<Enter_IPV_Designation>",
    "appIpvOrgan": "<Enter_IPV_Organization>",
    "appKycMode": "<Enter_KYC_Mode>",
    "appVerNo": "<Enter_Version_Number>",
    "appVidNo": "<Enter_VID_Number>",
    "appUidToken": "<Enter_UID_Token>",
    "appAuthName": "<Enter_Authorizer_Name>",
    "appAuthEmail": "<Enter_Authorizer_Email>",
    "appAuthEmail1": "<Enter_Alternate_Email_1>",
    "appAuthEmail2": "<Enter_Alternate_Email_2>",
    "appAuthMobile": "<Enter_Authorizer_Mobile>",
    "appAuthFpiConsent": "<Enter_FPI_Consent_Status>",
    "appAuthUboConsent": "<Enter_UBO_Consent_Status>",
    "noOfKycRecords": "<Enter_Number_of_KYC_Records>",
    "noOfAddldataRecords": "<Enter_Additional_Data_Records>",
    "pan": "<PAN_Document>",
    "aadhaar": "<Aadhaar_Document>",
    "applicationStatus": "<Enter_Application_Status>",
    "appFatcaApplicableFlag": "<Enter_FATCA_Applicability>"
}'

Success Response

The following code snippet demonstrates a success response from the API:

{
    "status": "success",
    "statusCode": "200",
    "result": {
        "kycdata": {
            "appPanNo": "<PAN_Number_Of_The_Applicant>",
            "appPanDob": "<Date_Of_Birth_Associated_With_PAN>",
            "appName": "<Name_Of_The_Applicant>",
            "appStatus": "<KYC_Application_Status>",
            "appModfAck": "<Modification_Acknowledgment_Flag>",
            "appStatusdt": "<Date_Of_KYC_Application_Status>",
            "appEntrydt": "<Date_Of_KYC_Record_Entry>",
            "appModdt": "<Date_Of_Last_Modification>",
            "appPosCode": "<Point_Of_Service_Code>"
        },
        "footer": {
            "appResponseDate": "<Timestamp_Of_The_Response>",
            "appTotalRec": "<Total_Number_Of_Records>"
        }
    },
    "metaData": {
        "requestId": "<Unique_Request_Identifier>",
        "transactionId": "<Transaction_Identifier>"
    }
}

Success Response Details

The following table outlines the details of the success response from the API:

Parameter	Type	Description
status	string	The status of the request
statusCode	string	The HTTP status code of the response
appPanNo	string	The PAN number associated with the KYC application
appPanDob	string	The date of birth linked to the provided PAN
appName	string	The name of the user or organization associated with the application
appStatus	string	Represents the initial status of the application
appModfAck	string	The acknowledgment flag for KYC modifications
appStatusdt	string	The date when the KYC application was initiated
appEntrydt	string	The date when the KYC application was entered into the system
appModdt	string	The date when the KYC application was last modified
appPosCode	string	POS code of the Asset Management Company (AMC) on whose behalf the request is being updated
appResponseDate	string	The date and time when the response was generated
appTotalRec	string	The total number of records in the response
requestId	string	The unique identifier for the request
transactionId	string	The unique identifier for the transaction

Error Responses

The following are some error responses from the API:

Invalid PAN format

{
    "status": "failure",
    "statusCode": "400",
    "message": "Invalid PAN format"
}

Invalid DOB

{
    "status": "failure",
    "statusCode": "400",
    "message": "Invalid DOB provided"
}

Invalid Record Count

{
    "status": "failure",
    "statusCode": "400",
    "message": "Invalid Record Count"
}

Invalid Request Details

{
    "status": "failure",
    "statusCode": "400",
    "message": "Invalid request details"
}

Duplicate Request

{
    "status": "failure",
    "statusCode": "400",
    "message": "Duplicate request"
}

Invalid Batch Size

{
    "status": "failure",
    "statusCode": "400",
    "message": "Invalid Batch Size" 
}

Invalid Batch Number

{
    "status": "failure",
    "statusCode": "400",
    "message": "Invalid / Expired Batch No" 
}

Missing/Invalid credentials

{
    "message": "Missing/Invalid credentials",
    "statusCode": 401,
    "status": "failure"
}

Unsupported Media Type

{
    "status": "failure",
    "statusCode": "415",
    "message": "Unsupported media type"
}

Internal Server Error

{
    "status": "failure",
    "statusCode": "500",
    "message": "Internal Server Error"
}

Invalid Details

{
    "status": "failure",
    "statusCode": "500",
    "message": "Invalid User ID / PosCode / Password / Access Privilege Not Set"
}

Invalid XML

{
    "status": "failure",
    "statusCode": "500",
    "message": "Invalid XML" 
}

Invalid POS Code

{
    "status": "failure",
    "statusCode": "500",
    "message": "Invalid Intermediary Code provided" 
}

Error Response Details

An error response from the module contains a failure status, with a relevant status code and error message.
The following table lists all error responses:

Status Code	Error Message	Error Description
400	Invalid PAN format	The PAN provided is not in the correct format. (‘CCCCCDDDDC’ format, where 'C' represents a character and 'D' represents a digit)
400	Invalid DOB provided	The date of birth provided is not valid
400	Invalid Record Count	The record count specified in the request is not valid
400	Invalid request details	The request details provided are incomplete or incorrect
400	Duplicate request	The request has already been submitted previously
400	Invalid Batch Size	The batch size is invalid
400	Invalid / Expired Batch No	The batch ID (a unique ID assigned by the KRA for each batch) is invalid
401	Missing/Invalid credentials	The request is either missing the mandatory appId and appKey combination or has invalid values
415	Unsupported media type	The media type provided in the request is not supported
500	Internal Server Error	Please check the request headers or contact the HyperVerge team for resolution
500	Invalid User ID / PosCode / Password / Access Privilege Not Set	The provided user credentials or access privileges are not correctly configured
500	Invalid XML	The Aadhaar XML file provided is not valid
500	Invalid Intermediary Code provided	The POS code of the AMC provided in the request is not valid

appStatus and appUpdtflg Mapping

Purpose: The following table provides a clear reference for selecting the appropriate appUpdtflg value based on the status of a user's KYC application. The status is identified by the Status field, which is returned by the CVL Search and Verify API.

Status	appUpdtflg
KYC rejected Existing KYC Hold Hold KRA Validated Modification Registered Modification Hold Modification Rejected Modification Validated	Modify with document In case the modification requires document proof, e.g., POA for verifying address
KRA Verified Existing KRA Verified	Modify without document In case the modification can be done without a document, e.g., verifying a phone number
Submitted Not available	New For fresh KYCs and rejected cases
If we have the following codes: 102/202/302/402 107/207/307/407 112/212/312/412 103/203/303/403 113/213/313/413	Interop Modification In case KYC details are found in other KRAs like NDML/Dotex/Karvy/CAMS and the user wants to modify details— we utilize Interop Modification

KRA Webhook

The KRA Webhook facilitates real-time updates by notifying users about changes to the KRA application status. It enables seamless monitoring of application progress and can automate downstream processes, including document verification, communication, or follow-up actions. Please access the documentation for KRA Webhook here .